Inside Macintosh: QuickTime /

Chapter 2 - Movie Toolbox / Movie Toolbox Reference

Functions for Editing Movies / Adding Samples to Media Structures

GetMediaSampleReference

The GetMediaSampleReference function allows your application to obtain reference information about samples that are stored in a movie data file.

pascal OSErr GetMediaSampleReference (Media theMedia, 
                     long *dataOffset,long *size, TimeValue time, 
                     TimeValue *sampleTime,
                     TimeValue *durationPerSample,
                     SampleDescriptionHandle sampleDescriptionH,
                     long *sampleDescriptionIndex,
                     long maxNumberOfSamples, 
                     long *numberOfSamples, short *sampleFlags);

theMedia

Specifies the media for this operation. Your application obtains this media identifier from such Movie Toolbox functions as NewTrackMedia and GetTrackMedia (described on page 2-138 and page 2-190, respectively).

dataOffset

Contains a pointer to a long integer. The GetMediaSampleReference function updates the field referred to by this parameter with the offset to the sample data.

This parameter is used differently by each media handler. For example, the hierarchical file system (HFS) media handler returns an offset into the file that contains the media data.

size

Contains a pointer to a long integer. The GetMediaSampleReference function updates the field referred to by the size parameter with the number of bytes of sample data referred to by the reference. Set this parameter to nil if you are not interested in this information.

time

Specifies the starting time of the sample reference to be retrieved. You must specify this value in the media's time scale.

sampleTime

Contains a pointer to a time value. The GetMediaSampleReference function updates this time value to indicate the actual time of the returned sample data. If you are not interested in this information, set this parameter to nil.

The returned time may differ from the time you specified with the time parameter. This will occur if the time you specified falls in the middle of a sample.

durationPerSample

Contains a pointer to a time value. The Movie Toolbox returns the duration of each sample in the media. This time value is expressed in the media's time scale. Set this parameter to 0 if you do not want this information.

sampleDescriptionH

Contains a handle to a sample description. The GetMediaSampleReference function returns the sample description corresponding to the returned sample data. The function resizes this handle as appropriate. If you do not want the sample description, set this parameter to nil.

sampleDescriptionIndex

Contains a pointer to a long integer. The GetMediaSampleReference function returns an index value to the sample description that corresponds to the returned sample data. You can use this index to retrieve the media sample description with the GetMediaSampleDescription function, which is described on page 2-210. If you do not want this information, set this parameter to nil.

You can retrieve the sample description itself by using the sampleDescriptionH parameter.

maxNumberOfSamples

Specifies the maximum number of samples to be returned. The Movie Toolbox does not return a reference that refers to more samples than you specify with this parameter.

If you set this parameter to 0, the Movie Toolbox uses a value that is appropriate for the media and returns that value in the field referenced by the numberOfSamples parameter.

numberOfSamples

Contains a pointer to a long integer. The GetMediaSampleReference function updates the field referred to by this parameter with the number of samples referred to by the returned reference. If you do not want this information, set this parameter to nil.

sampleFlags

Contains a pointer to a short integer. The GetMediaSampleReference function returns flags that describe the samples referred to by the reference. The following flag is available (unused flags are set to 0):

mediaSampleNotSync

Indicates the sample that is returned is not a sync sample. Set this flag to 1 if the sample is not a sync sample. Set this flag to 0 if the sample is a sync sample.

If you do not want this information, set this
parameter to nil.

DESCRIPTION

The GetMediaSampleReference function is similar to GetMediaSample, except that it does not return the sample data.

ERROR CODES

invalidMedia

-2008

This media is corrupted or invalid

Memory Manager errors